home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 August: Tool Chest / Dev.CD Aug 98 TC.toast / Sample Code / Games / MoofWars / Tim's Libraries / TGraphicCollection.h < prev   
Encoding:
C/C++ Source or Header  |  1996-08-19  |  6.7 KB  |  164 lines  |  [TEXT/CWIE]
  1. /*************************************************************************************
  2. #
  3. #    TGraphicCollection.cp
  4. #    
  5. #
  6. #    The TGraphicCollection class is a group of related TGraphic objects.  Essentially,
  7. #   the API for this class mimics the TGraphic class very closely, except that all of
  8. #   the routines in TGraphicCollection pass in an index to which TGraphic object is being
  9. #   referred to.
  10. #
  11. #    Because this class relies so heavily on TGraphic, we share all of TGraphic's
  12. #    limitations.  In fact, any of the routines used to prepare drawing in TGraphic are
  13. #    used without modification, since they apply to ALL TGraphic objects, regardless of
  14. #    if they are in a collection or not.
  15. #
  16. #    Note that this class isn't currently intended to be subclassed, so all of the methods
  17. #    are non-virtual.  This might change if at some point we determine we need to create
  18. #    a subclass.#
  19. #
  20. #    Author: Timothy Carroll
  21. #    Apple Developer Technical Support
  22. #    timc@apple.com
  23. #
  24. #    Modification History: 
  25. #
  26. #    6/1/96        TMC     Initial Release
  27. #
  28. #    Copyright © 1996 Apple Computer, Inc., All Rights Reserved
  29. #
  30. #
  31. #    You may incorporate this sample code into your applications without
  32. #    restriction, though the sample code has been provided "AS IS" and the
  33. #    responsibility for its operation is 100% yours.  However, what you are
  34. #    not permitted to do is to redistribute the source as "DSC Sample Code"
  35. #    after having made changes. If you're going to re-distribute the source,
  36. #    we require that you make it clear in the source that the code was
  37. #    descended from Apple Sample Code, but that you've made changes.
  38. #
  39. *************************************************************************************/
  40.  
  41.  
  42. #ifndef _TGRAPHICCOLLECTION_
  43. #define _TGRAPHICCOLLECTION_
  44.  
  45. #pragma once
  46.  
  47. #include "TGraphic.h"
  48.  
  49. #if PRAGMA_ALIGN_SUPPORTED
  50. #pragma options align=power
  51. #endif
  52.  
  53. // To provide an smaller, simpler interface, we'll define a couple of macros here. Their use is optional.
  54.  
  55. #define NewGraphicCollection(resID) TGraphicCollection::NewCollection((resID))
  56. #define DisposeGraphicCollection(collection) (collection)->DisposeReference()
  57.  
  58.  
  59.  
  60.  
  61. class TGraphicCollection
  62. {
  63.     public:
  64. /****************************************************************************************************
  65.     Static Creator and Reference Counting
  66.     
  67.     These are the routines that handle the actual creation of the objects, along with reference
  68.     counting and so on.  You shouldn't need to call the reference counting routines yourself --
  69.     instead, call the macros to create and destroy collections and they'll do the right thing.
  70.     
  71.     Note that DisposeReference is the routine actually responsible for destroying a collection
  72.     when we're through.
  73.     
  74.     A TGraphicCollection is currently defined by a resource of type 'SptA' or sprite array.
  75. ****************************************************************************************************/
  76.     static TGraphicCollection     *NewCollection (SInt16 resID);
  77.  
  78.     void    AddReference (void);
  79.     void    DisposeReference (void);
  80.     
  81.     
  82.     
  83. /****************************************************************************************************
  84.     Locking and Unlocking
  85.     
  86.     You are never required to lock a collection -- the routines run fine either way.  We provide these
  87.     functions because the main use of this class is for drawing sprites.  In a game, most of the
  88.     graphics will be allocated ahead of time and stick around until the game ends.  By locking them
  89.     down high, we ensure they won't need to be moved to make room for other handles that might need
  90.     to be allocated.
  91. ****************************************************************************************************/
  92.     OSErr    LockCollection (void);
  93.     OSErr    UnlockCollection (void);
  94.     
  95.     
  96. /****************************************************************************************************
  97.     Creating and destroying the collection
  98.     
  99.     The actual work to create and destroy the collection is done in the following two routines.
  100.     CreateCollection loads the resource, gets the data and creates any TGraphic objects necessary
  101.     for the collection.  DestroyCollection simply reverses the process.
  102. ****************************************************************************************************/
  103.     OSErr    CreateCollection (void);
  104.     OSErr    DestroyCollection (void);
  105.     
  106.     
  107. /****************************************************************************************************
  108.     Accessor Functions
  109.     
  110.     We define a few accessor functions to allow clients to get some information.  At this point, we
  111.     are advertising the TGraphics as something that can be obtained.  We do not immediatly force
  112.     a link to the TGraphic object when we send it to you.  If you want a persistant link to the
  113.     TGraphic object, you must create a link to it and properly dispose of it.  Otherwise, make sure
  114.     you don't destroy the TGraphicCollection until you are done with the TGraphic.
  115. ****************************************************************************************************/
  116.  
  117. // We'll inline the first function for speed.
  118.     SInt16            GetResID(void) {return fResID;}
  119.     Rect            GetBounds (UInt32 index);
  120.     TGraphic        *GetTGraphic (UInt32 index); // returns a naked TGraphic.  Use sparingly.
  121.     
  122.     
  123. /****************************************************************************************************
  124.     Utility Functions
  125.     
  126.     The main routines that TGraphic is known for.  I won't explain them in detail here, check out
  127.     the TGraphic class for details.
  128. ****************************************************************************************************/
  129.     void            CopyImage (UInt32 index, SInt32 top, SInt32 left, Boolean useBackground);                                   
  130.     Boolean            HitTest (UInt32 index, SInt32 v, SInt32 h);
  131.     
  132.  
  133. protected:
  134.     
  135.         
  136. /****************************************************************************************************
  137.     Constructor/Destructor
  138.     
  139.     The contructor and destructor shouldn't be called except internally by the class, so they
  140.     have been made protected.  The class does reference counting, and only calls the destructors when all clients
  141.     are through with a class.  If you call it yourself, Bad Things Happen.
  142. ****************************************************************************************************/
  143.     TGraphicCollection (SInt16 resID);
  144.     ~TGraphicCollection (void);
  145.  
  146.     
  147. /****************************************************************************************************
  148.     Data Structures
  149.     
  150.     The actual data used to hold the TGraphicCollection.  We make sure that the data is aligned
  151.     properly for both PowerPC and 68K struct alignment.
  152. ****************************************************************************************************/
  153.  
  154.     Handle            fGraphics;           // 4 bytes
  155.     SInt16            fResID;            // 2 bytes
  156.     UInt16            fReferenceCount;   // 2 bytes, # of owners of this collection;
  157.     UInt32            fNumberOfGraphics; // 4 bytes
  158. };
  159.  
  160. #if PRAGMA_ALIGN_SUPPORTED
  161. #pragma options align=reset
  162. #endif
  163.  
  164. #endif /* _TGRAPHICCOLLECTION_ */